docs: clarify three-state include/exclude_half.life semantics#556
Merged
Conversation
The TRUE/FALSE/NA semantics of include_half.life and exclude_half.life, and the rule that only one may be in use per interval, were not documented in the function/argument reference. This left it unclear that initializing a column to all-FALSE (rather than NA) engages that mechanism and can trigger "Cannot both include and exclude half-life points for the same interval" when downstream code also sets inclusions. - Document the three per-point states (TRUE acts, FALSE does not, NA undefined) and the "in use unless entirely NA" activation rule in the roxygen for PKNCAconc() and pk.nca.interval(); regenerate man pages. - Add the mutual-exclusivity note to the half-life vignette and fix a mislabeled "include" example (section text + chunk comments). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Make explicit that exclude_half.life does NOT bypass automatic curve-stripping point selection -- it drops the flagged points, and curve stripping still runs on the remaining points -- while include_half.life bypasses curve stripping and names the exact points to use. Replace the generic "TRUE acts on the point" phrasing with the per-column meaning (TRUE uses/excludes the point). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The
TRUE/FALSE/NAsemantics ofinclude_half.life/exclude_half.life, andthe rule that only one may be in use per interval, were not in the argument
reference. This made it non-obvious that initializing a column to all-
FALSE(instead of
NA) engages that mechanism, which can trigger "Cannot both includeand exclude half-life points for the same interval" when inclusions are also set.
(Surfaced by an aNCA revdep check against dev PKNCA.)
Changes
PKNCAconc(),pk.nca.interval()): document the threeper-point states (
TRUEacts,FALSEdoes not,NAundefined), the activationrule (a column is "in use" unless entirely
NA, so an all-FALSEcolumn stillcounts), and the mutual-exclusivity rule.
v06): add the same note; fix a mislabeledinclude_half.lifeexample (intro text said "exclude"; chunk comments were copied from the exclude case).
Documentation only — no behavior change.
🤖 Generated with Claude Code